.\" $Id: PAPI_get_opt.3,v 1.18.4.1 2006/10/27 19:47:14 terpstra Exp $
.TH PAPI_get_opt 3 "October, 2006" "PAPI Programmer's Reference" "PAPI"

.SH NAME
 PAPI_get_opt \- get PAPI library or event set options
 PAPI_set_opt \- set PAPI library or event set options
 PAPIF_get_clockrate \- get the clockrate (Fortran only)
 PAPIF_get_domain \- get the counting domain (Fortran only)
 PAPIF_get_granularity \- get the counting granularity (Fortran only)
 PAPIF_get_preload \- get the library preload setting (Fortran only)

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_get_opt(int " option ", PAPI_option_t *" ptr ");"
.BI "int PAPI_set_opt(int " option ", PAPI_option_t *" ptr ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_get_clockrate(C_INT\  clockrate )
.BI PAPIF_get_domain(C_INT\  EventSet,\  C_INT\  domain,\  C_INT\  mode,\  C_INT\  check )
.BI PAPIF_get_granularity(C_INT\  EventSet,\  C_INT\  granularity,\  C_INT\  mode,\  C_INT\  check )
.BI PAPIF_get_preload(C_STRING\  preload,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B PAPI_get_opt()
and
.B PAPI_set_opt() 
query or change the options of the PAPI library or a specific event set 
created by
.BR "PAPI_create_eventset" (3).
The C interface for these functions passes a pointer to the
.I PAPI_option_t
structure. Not all options require or return information in this structure,
and not all options are implemented for both get and set.

The Fortran interface is a series of calls implementing various subsets of
the C interface. Not all options in C are available in Fortran.
.LP
.B NOTE:
Some options, such as PAPI_DOMAIN and PAPI_MULTIPLEX, are also 
available as separate entry points in both C and Fortran.
.LP
The reader is urged to see the example code in the PAPI distribution
for usage of PAPI_get_opt.  The file 
.B papi.h 
contains definitions for the structures unioned in the  
.I PAPI_option_t
structure.


.SH ARGUMENTS
.I option
-- is an input parameter describing the course of action. Possible
values are defined in 
.B papi.h
and briefly described in the table below. The Fortran calls are
implementations of specific options.
.LP
.I "ptr"
-- is a pointer to a structure that acts as both an input and output parameter. 
It is defined in
.B papi.h
and  below.
.LP
.I EventSet 
-- input; a reference to an EventSetInfo structure
.LP
.I clockrate
--  output; cycle time of this CPU in MHz; *may* be an estimate
generated at init time with a quick timing routine
.LP
.I domain
--  output; execution domain for which events are counted
.LP
.I granularity
--  output; execution granularity for which events are counted
.LP
.I mode
--  input; determines if domain or granularity are default 
or for the current event set
.LP
.I preload
--  output; environment variable string for preloading libraries

.SH OPTIONS TABLE
.LP
.TS H
allbox tab($);
cB cB
cI s
lB lw(45).
.TH
Predefined name$Explanation
General information requests
PAPI_CLOCKRATE$T{
Get clockrate in MHz.
T}
PAPI_MAX_CPUS$T{
Get number of CPUs.
T}
PAPI_MAX_HWCTRS$T{
Get number of counters.
T}
PAPI_EXEINFO$T{
Get Executable addresses for text/data/bss.
T}
PAPI_HWINFO$T{
Get information about the hardware.
T}
PAPI_SHLIBINFO$T{
Get shared library information used by the program.
T}
PAPI_SUBSTRATEINFO$T{
Get the PAPI features the substrate supports
T}
PAPI_LIB_VERSION$T{
Get the full PAPI version of the library
T}
PAPI_PRELOAD$T{
Get ``LD_PRELOAD'' environment equivalent.
T}
.T&
cI s
lB lw(45).
Defaults for the global library
PAPI_DEFDOM$T{
Get/Set default counting domain for newly created event sets.
T}
PAPI_DEFGRN$T{
Get/Set default counting granularity.
T}
PAPI_DEBUG$T{
Get/Set the PAPI debug state and the debug handler. The available debug states are
defined in papi.h. The debug state is available in ptr->debug.level. The debug
handler is available in ptr->debug.handler. For information regarding the behavior
of the handler, please see the man page for PAPI_set_debug.
T}
.T&
cI s
lB lw(45).
Multiplexing control
PAPI_MULTIPLEX$T{
Get/Set options for multiplexing. 
T}
PAPI_MAX_MPX_CTRS$T{
Get maximum number of multiplexing counters. 
T}
PAPI_DEF_MPX_USEC$T{
Get/Set the sampling time slice in microseconds for multiplexing. 
T}
.T&
cI s
lB lw(45).
Manipulating individual event sets
PAPI_ATTACH$T{
Get thread or process id to which event set is attached. Returns TRUE
if currently attached.
Set event set specified in ptr->ptr->attach.eventset 
to be attached to thread or process id specified in
in ptr->attach.tid
T}
PAPI_DETACH$T{
Get thread or process id to which event set is attached. Returns TRUE
if currently detached.
Set event set specified in ptr->ptr->attach.eventset 
to be detached from any thread or process id.
T}
PAPI_DOMAIN$T{
Get/Set domain for a single event set. The event set is specified 
in ptr->domain.eventset
T}
PAPI_GRANUL$T{
Get/Set granularity for a single event set. The event set is specified 
in ptr->granularity.eventset. Not implemented yet.
T}
.T&
cI s
lB lw(45).
Platform specific options
PAPI_DATA_ADDRESS$T{
Set data address range to restrict event counting for event set specified 
in ptr->addr.eventset. Starting and ending addresses are specified in 
ptr->addr.start and ptr->addr.end, respectively. If exact addresses cannot
be instantiated, offsets are returned in ptr->addr.start_off and
ptr->addr.end_off. Currently implemented on Itanium only.
T}
PAPI_INSTR_ADDRESS$T{
Set instruction address range as described above. Itanium only.
T}
.TE

.LP
The 
.BI option_t\ *  ptr
structure is defined in 
.B papi.h
and looks something like the following example from the source tree.
Users should use the definition in 
.B papi.h
which is in synch with the library used.
.LP
.nf
.if t .ft CW
typedef union {
  PAPI_preload_option_t preload;
  PAPI_debug_option_t debug;
  PAPI_granularity_option_t granularity; 
  PAPI_granularity_option_t defgranularity; 
  PAPI_domain_option_t domain; 
  PAPI_domain_option_t defdomain; 
  PAPI_attach_option_t attach;
  PAPI_multiplex_option_t multiplex;
  PAPI_hw_info_t *hw_info;
  PAPI_shlib_info_t *shlib_info;
  PAPI_exe_info_t *exe_info;
  PAPI_substrate_info_t *sub_info;
  PAPI_overflow_option_t ovf_info;
  PAPI_addr_range_option_t addr;
} PAPI_option_t;
.if t .ft P
.fi

.SH RETURN VALUES
On success, these functions return
.I "PAPI_OK."
On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_ENOEVST"
The event set specified does not exist.
.TP
.B "PAPI_EISRUN"
The event set is currently counting events.

.SH EXAMPLES
.LP
.nf
.if t .ft CW
PAPI_option_t options;

if ((num = PAPI_get_opt(PAPI_MAX_HWCTRS,NULL)) <= 0)
  handle_error();

printf("This machine has %d counters.\n",num);

/* Set the domain of this EventSet 
   to counter user and kernel modes for this
   process */
	
memset(&options,0x0,sizeof(options));
options.domain.eventset = EventSet;
options.domain.domain = PAPI_DOM_ALL;
if (PAPI_set_opt(PAPI_DOMAIN, &options) != PAPI_OK)
  handle_error();
.if t .ft P
.fi

.SH BUGS
The granularity functions are not yet implemented.
The domain functions are only implemented on some platforms.
There are no known bugs in these functions.

.SH SEE ALSO
.BR PAPI_set_debug "(3)," PAPI_set_multiplex "(3)," PAPI_set_domain "(3)"
